5 Schema и взаимосвязь артефактов
Глава 5: Schema и взаимосвязь артефактов
В данной главе описывается структура артефактов проекта CAP, определяется центральная роль файлов определения Schema протокола в системе артефактов, а также соответствие между версиями Schema и версиями протокола. Понимание иерархических отношений и зависимостей между артефактами является основой для участия разработчиков реализаций протокола и участников сообщества в совместной работе над проектом.
5.1 Три категории основных артефактов
Система артефактов проекта CAP состоит из трёх категорий основных артефактов, формирующих полную цепочку поставки от документации к определению и реализации:
| Категория артефактов | Описание | Пример пути в репозитории |
|---|---|---|
| Многоязычная документация протокола | Включает архитектурный план (Blueprint) и техническую спецификацию протокола (Specification), публикуемые эквивалентно на 9 языках, предоставляя человекочитаемое описание замысла проектирования, области возможностей и технических деталей протокола | docs/{lang}/blueprint/, docs/{lang}/specification/ |
| Файлы определения Schema протокола | Авторитетное определение формата сообщений протокола, предоставляемое в нескольких машиночитаемых и человекочитаемых форматах, являющееся эталоном для реализации SDK и тестирования совместимости | schema/{version}/ |
| Реализации SDK на различных языках | Конкретные реализации протокола на различных языках программирования, разработанные на основе файлов определения Schema, предоставляющие готовые к использованию возможности интеграции протокола для разработчиков различных технологических стеков | sdk/{language}/ |
Иерархические отношения между тремя категориями артефактов:
- Многоязычная документация протокола находится на стратегическом и нормативном уровне, определяя верхнеуровневый дизайн «что делает» и «как делает» протокол
- Файлы определения Schema протокола находятся на уровне определения, преобразуя форматы сообщений из спецификации протокола в точные, машинообрабатываемые формальные определения
- Реализации SDK на различных языках находятся на уровне реализации, преобразуя возможности протокола на основе файлов определения Schema в непосредственно вызываемые программные интерфейсы
Обновление трёх категорий артефактов следует нисходящему пути распространения: изменения в документации протокола инициируют обновление определений Schema, обновление определений Schema инициирует адаптацию реализаций SDK.
5.2 Роль файлов определения Schema
Файлы определения Schema являются авторитетным определением (Authoritative Definition) формата сообщений протокола CAP и выполняют следующие ключевые функции в системе артефактов проекта:
- Единственный источник истины (Single Source of Truth) для формата сообщений: Файлы определения Schema точно описывают имена полей, типы данных, ограничения обязательности/необязательности и вложенные структуры всех типов сообщений протокола CAP. При наличии неоднозначности между текстовым описанием документации протокола и определением Schema приоритет имеет определение Schema
- Эталон разработки для реализации SDK: Логика сериализации/десериализации сообщений в SDK на различных языках должна строго соответствовать определению Schema. Разработчики SDK через файлы определения Schema узнают точную структуру каждого типа сообщений, обеспечивая полную согласованность формата сообщений между реализациями SDK на различных языках
- Эталон проверки для тестирования совместимости: Тестирование совместимости между SDK на различных языках использует определение Schema в качестве стандарта проверки. Сообщение, сериализованное одним SDK, должно быть корректно десериализовано другим SDK; файл определения Schema является единственным критерием определения «корректности»
- Основа для автоматизированной верификации: Файлы определения Schema (особенно schema.json) могут непосредственно использоваться инструментами автоматизации для автоматической проверки формата сообщений, генерации кода и генерации документации, снижая количество ошибок, допускаемых вручную
5.3 Соответствие версий Schema и версий протокола
Каждая официально выпущенная версия протокола CAP соответствует одной версии Schema; файлы Schema хранятся в каталоге, названном по дате выпуска версии протокола, обеспечивая чёткую и отслеживаемую связь версий.
Правила именования каталогов:
| Статус протокола | Каталог Schema | Описание |
|---|---|---|
| Черновик (Draft) | schema/draft/ | Разрабатываемые определения Schema, могут изменяться в любое время, без гарантии совместимости |
| Официальный выпуск | schema/{ГГГГ-ММ-ДД}/ | Именуется по дате выпуска, например schema/2025-10-25/; после выпуска не подлежит изменению (immutable) |
Правила соответствия версий:
- Соответствие один к одному: Каждая официально выпущенная версия протокола соответствует ровно одному каталогу версии Schema; имя каталога использует дату выпуска данной версии протокола
- Общий черновик: Все изменения Schema на этапе черновика используют общий каталог
schema/draft/; на этапе черновика версии не различаются - Неизменяемость: Файлы в каталоге Schema официально выпущенной версии после выпуска больше не изменяются. Любые изменения Schema (включая исправление ошибок) осуществляются через выпуск новой версии
- Сохранение истории: Каталоги Schema старых версий навсегда сохраняются в репозитории для исторической справки и верификации обратной совместимости
Текущее соответствие версий:
| Версия протокола | Каталог Schema | Статус |
|---|---|---|
| draft | schema/draft/ | В разработке |
| 2025-10-25 | schema/2025-10-25/ | Выпущена |
5.4 Описание форматов файлов Schema
Каждый каталог версии Schema содержит файлы определения Schema в 3 форматах, предназначенных для различных сценариев использования и потребителей:
| Формат | Имя файла | Назначение | Основные потребители |
|---|---|---|---|
| JSON Schema | schema.json | Машиночитаемое определение формата сообщений для автоматизированной верификации, генерации кода и проверки межъязыковой совместимости | Инструменты автоматизации, конвейеры CI/CD, генераторы кода SDK |
| TypeScript | schema.ts | Определения типов TypeScript, обеспечивающие нативную поддержку типов для экосистемы TypeScript/JavaScript, используемые для разработки TS/JS SDK и проверки типов в IDE | Разработчики TypeScript/JavaScript SDK, разработчики фронтенд-интеграции |
| MDX | schema.mdx | Формат документации с возможностью рендеринга, представляющий определения Schema в удобном для человека виде, используемый для отображения на сайте документации и изучения протокола | Изучающие протокол, сайт документации, технические рецензенты |
Взаимосвязь трёх форматов:
- schema.json является авторитетным форматом: При наличии расхождений между тремя форматами приоритет имеет schema.json. schema.ts и schema.mdx должны поддерживать семантическую согласованность с schema.json
- schema.ts является форматом для удобства разработки: schema.ts преобразует определения типов из schema.json в нативные типы TypeScript, позволяя разработчикам TS/JS получать подсказки типов и проверку на этапе компиляции непосредственно в IDE
- schema.mdx является форматом для отображения: schema.mdx преобразует структурированные определения из schema.json в содержимое документации с возможностью рендеринга, поддерживая интерактивный просмотр определений Schema на сайте документации
Пример структуры каталогов файлов:
schema/
├── draft/
│ ├── schema.json
│ ├── schema.ts
│ └── schema.mdx
└── 2025-10-25/
├── schema.json
├── schema.ts
└── schema.mdx